/*
 * Copyright 2008-2009 Daniel Freitas
 * 
 * This file is part of Army Creator.
 * 
 * Army Creator is free software: you can redistribute it and/or modify it under the terms of the GNU General Public
 * License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later
 * version.
 * 
 * Army Creator is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
 * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License along with Army Creator. If not, see
 * <http://www.gnu.org/licenses/>.
 */
package com.googlecode.armycreator.datastore.genericdao;

import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Transactional;

import java.util.List;

/**
 * Provides a common interface for basic CRUD operations and queries.
 * 
 * @author <a href="mailto:daniel.mfreitas@gmail.com">Daniel Freitas</a>
 * @param <T>
 *            The domain object this DAO is responsible for.
 */
public interface GenericDao<T> {

    /**
     * Finds all object instances of the specified type.
     * 
     * @return A {@link List} containing all objects from the given class stored in the persistence layer, in no
     *         particular order.
     */
    @Transactional(propagation = Propagation.REQUIRED, readOnly = true)
    public List<T> findAll();

    /**
     * Finds all objects similar to the given example. In other words, finds all objects which property values match the
     * example's properties. Optionally, it is possible to filter properties from the criteria by providing their names
     * to the vararg argument. The object identifier is never used in the comparison.
     * 
     * @param example
     *            The object instance to be used as an example.
     * @param excludeProperty
     *            The properties to be ignored in the comparison.
     * 
     * @return A list with all the objects that matches the given example.
     */
    @Transactional(propagation = Propagation.REQUIRED, readOnly = true)
    public List<T> findByExample(T example, String... excludeProperty);

    /**
     * Finds a domain object by its identifier.
     * 
     * @param id
     *            The object id to be queried for.
     * 
     * @return The object of the specified type whose id matches the given key, or null if the id cannot be found.
     */
    @Transactional(propagation = Propagation.REQUIRED, readOnly = true)
    public T findById(Long id);

    /**
     * Synchronizes the object state to the underlying persistence storage, propagating changes made in the object.
     * 
     * @param o
     *            The object to be saved.
     * 
     * @return The object that has been made persistent. If the object was a new instance, the id property is now
     *         populated.
     */
    @Transactional(propagation = Propagation.REQUIRED)
    public T makePersistent(T o);

    /**
     * Removes the domain object instance from the persistence layer.
     * 
     * @param o
     *            The object to be removed.
     */
    @Transactional(propagation = Propagation.REQUIRED)
    public void makeTransient(T o);
}
